Messages and Context
Two ideas explain most of how Node-RED works: messages carry data from node to node, and context remembers data between messages. This page covers both.
Messages
A message is a JavaScript object. Nodes pass messages along wires, and each node can read, change, or replace the message it receives. By convention the main data is in msg.payload, and other properties describe it.
{
"_msgid": "6b8f3a1c2d4e5f60",
"topic": "sensor.kitchen_temperature",
"payload": 71.4
}
| Property | Meaning |
|---|---|
payload | The main data. It can be a string, number, boolean, object, array, or buffer. |
topic | An optional label for the message. Some nodes use it to group or route messages. |
_msgid | A unique ID Node-RED adds so it can follow a message through the flow. Leave it alone. |
Nodes add their own properties too. For example, a Home Assistant state node adds msg.data with the event details. Always check a node's Help tab in the sidebar to see what it sets.
Look at a message
Wire a debug node to the output of any node and deploy. Click a message in the Debug sidebar to expand it and see every property. This is the quickest way to learn what a node really sends.
Read and write properties
Property names use JavaScript's dot and bracket notation:
| Expression | Reads |
|---|---|
msg.payload | The payload. |
msg.payload.temperature | A property inside an object payload. |
msg.payload[0] | The first item of an array payload. |
msg["my-property"] | A property whose name has characters like - that dot notation can't handle. |
In a node's settings you will often see a typed input: a small drop-down next to a field that says what kind of value to use. The common types are:
| Type | Example | Meaning |
|---|---|---|
msg. | msg.payload | A property of the current message. |
flow. | flow.mode | A value from flow context. |
global. | global.house | A value from global context. |
string, number, boolean | on | A fixed value. |
JSON | {"a":1} | A fixed object or array. |
timestamp | The current time, in milliseconds. | |
env variable | TZ | An environment variable. |
JSONata | $now() | The result of a JSONata expression, evaluated against the message. |
Messages are copied
If one output is wired to several nodes, each of them gets its own copy of the message. Changing the message in one branch doesn't affect the others, so you don't have to worry about branches interfering.
Context
A message only lives while it travels through the flow. Context is a store that lasts longer, so you can keep a counter, remember the last value, or share a setting between flows.
Scopes
| Scope | Visible to | Use it for |
|---|---|---|
| Node | Only that node. | Private state, such as the last value a function node saw. |
| Flow | Every node on the same tab. | Values several nodes on one tab share. |
| Global | Every node on every tab. | Settings and values shared across the whole system. |
You can read and write context in two places:
- Function nodes use the
context,flow, andglobalobjects. See context and timers. - Change and switch nodes can set or test
flow.andglobal.values using a typed input, with no code at all. For example, achangenode can setflow.modeto the stringaway, and aswitchnode can test it later.
Look at stored values
Open the Context data tab in the sidebar and press the refresh button for a scope. Seeing the actual stored values is the fastest way to find out why a flow isn't behaving.
Memory and persistent storage
By default context is kept in memory. It is fast, but the values are lost when Node-RED restarts. It can also be cleared by a deploy, depending on the deploy type and what changed, so don't rely on it for anything you can't recreate.
To keep values across restarts, add a persistent store in settings.js:
contextStorage: {
default: { module: "memory" },
persistent: { module: "localfilesystem" }
},
Restart Node-RED, then name the store when you read or write a value:
flow.set("mode", "away", "persistent");
const mode = flow.get("mode", "persistent");
Values in a file-based store are saved to disk in the Node-RED data folder. Store plain data such as strings, numbers, arrays, and simple objects. Functions and timer handles can't be saved, so keep those in memory.
If you turn on Enable Global Context Store in the Home Assistant server node, the current state of every entity is available in global context. See Home Assistant nodes.
💬 Recent Comments